.\" $Id: PAPI_get_event_info.3,v 1.7 2005/05/19 19:37:47 terpstra Exp $
.TH PAPI_get_event_info 3 "September, 2004" "PAPI Programmer's Reference" PAPI

.SH NAME
PAPI_get_event_info \- get the event's name and description info

.SH SYNOPSIS
.B C Interface
.nf
.B #include <papi.h>
.BI "int PAPI_get_event_info(int EventCode, PAPI_event_info_t *info);"
.fi
.B Fortran Interface
.nf
.B #include "fpapi.h"
.BI PAPIF_get_event_info(C_INT\  EventCode,\  C_STRING\  symbol,
.BI \tC_STRING\ long_descr,\ C_STRING\  short_descr,\  C_INT\  count,
.BI \tC_STRING\ event_note,\ C_INT\  flags, ,\ C_INT\  check)
.fi

.SH DESCRIPTION
In C, this function fills the event information into a structure.
In Fortran, some fields of the structure are returned explicitly.
This function works with existing PAPI preset and native event codes.

.SH ARGUMENTS
The following arguments are implicit in the structure returned by the C function,
or explicitly returned by Fortran.
.LP
.I EventCode
--  event code(preset or native)
.LP
.I info
--  structure with the event information
.LP
.I symbol
--  whether the preset is part of the API
.LP
.I long_descr
--  detail description about the event
.LP
.I short_descr
--  short description about the event
.LP
.I event_note
--  notes about the event

.SH RETURN VALUES
On success, the C function returns PAPI_OK, 
and the Fortran function returns 
.B PAPI_OK.
 On error, a non-zero error code is returned by the function.

.SH ERRORS
.TP
.B "PAPI_EINVAL"
One or more of the arguments is invalid.
.TP
.B "PAPI_ENOTPRESET"
The PAPI preset mask was set, but the hardware event specified 
is not a valid PAPI preset.
.TP
.B "PAPI_ENOEVNT"
The PAPI preset is not available on the underlying hardware.



.SH EXAMPLE
.LP
.nf
.if t .ft CW
/*Find the event code for PAPI_TOT_INS and its info*/
PAPI_event_name_to_code("PAPI_TOT_INS",&EventCode)
if (PAPI_get_event_info(EventCode, &info) == PAPI_OK)
  handle_error(1);
.if t .ft P
.fi

.SH BUGS
This function has no known bugs.

.SH SEE ALSO
.BR PAPI "(3)," 
.BR PAPIF "(3)," 
.BR PAPI_set_event_info "(3)",
.BR PAPI_event_name_to_code "(3)" 
